Vault: Revamp audit logging docs #631
Open
+583
−370
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Rearrange the order of sections in the main Audit Logging documentation to keep related content closer together.
Remove the paragraph on blocking audit device failures. This content predates the rearchitecture of Vault's audit logging system and is no longer relevant. Vault's audit logging pipeline currently enforces a 10-second timeout for all audit devices.
Fix links to related concepts and API documentation. Add a note to recommend that users test the performance impact of their filtering rules in a non-production environment before deploying to production.
Vercel Previews Deployed
|
Broken Link CheckerNo broken links found! 🎉 |
schavis
requested changes
Jul 24, 2025
Comment on lines
68
to
72
| You should configure monitoring and alerting on the health of your audit devices. | ||
|
|
||
| Vault produces several [telemetry metrics](/vault/docs/internals/telemetry/metrics/audit) related to audit logging. You should especially monitor `vault.audit.log_request_failure`, `vault.audit.log_response_failure`, `vault.audit.{DEVICE}.log_request`, and `vault.audit.{DEVICE}.log_response` for spikes, which can indicate one or more audit devices failing. | ||
|
|
||
| Additionally, you should configure monitoring and alerting specific to each type of audit device, such as available disk space, disk IOPS, and log rotation status for `file` audit devices. |
There was a problem hiding this comment.
Suggested change
| You should configure monitoring and alerting on the health of your audit devices. | |
| Vault produces several [telemetry metrics](/vault/docs/internals/telemetry/metrics/audit) related to audit logging. You should especially monitor `vault.audit.log_request_failure`, `vault.audit.log_response_failure`, `vault.audit.{DEVICE}.log_request`, and `vault.audit.{DEVICE}.log_response` for spikes, which can indicate one or more audit devices failing. | |
| Additionally, you should configure monitoring and alerting specific to each type of audit device, such as available disk space, disk IOPS, and log rotation status for `file` audit devices. | |
| We strongly recommend monitoring and alerting on the health of your audit | |
| devices, with specific alerts for each type of audit device. For example, | |
| alerting on available disk space, disk IOPS, and log rotation status for `file` | |
| audit devices. | |
| Vault produces several audit logging | |
| [telemetry metrics](/vault/docs/internals/telemetry/metrics/audit) and we | |
| recommend monitoring the following metrics for spikes, which can indicate one or | |
| more audit devices failing: | |
| - [`vault.audit.log_request_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_request_failure) | |
| - [`vault.audit.log_response_failure`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-log_response_failure) | |
| - [`vault.audit.{DEVICE}.log_request`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_request) | |
| - [`vault.audit.{DEVICE}.log_response`](/vault/docs/internals/telemetry/metrics/audit#vault-audit-device-log_response) |
Comment on lines
76
to
80
| For each authentication backend and secrets engine mount you configure in Vault, you should evaluate which request and response attributes need *not* be [hashed](/vault/docs/audit#hashing-of-sensitive-values) in the audit logs. | ||
|
|
||
| <Tip> | ||
| Hashing should be left on for attributes that are sensitive (e.g., passwords, private keys) or that may be excessively large for your audit log. | ||
| </Tip> |
There was a problem hiding this comment.
Suggested change
| For each authentication backend and secrets engine mount you configure in Vault, you should evaluate which request and response attributes need *not* be [hashed](/vault/docs/audit#hashing-of-sensitive-values) in the audit logs. | |
| <Tip> | |
| Hashing should be left on for attributes that are sensitive (e.g., passwords, private keys) or that may be excessively large for your audit log. | |
| </Tip> | |
| We recommend [hashing](/vault/docs/audit#hashing-of-sensitive-values) for all | |
| sensitive attributes (for example, passwords and private keys) and any attribute | |
| may be excessively large for your audit log. | |
| For all other attributes, we recommend reviewing each authentication backend and | |
| secrets engine mount you configure in Vault to evaluate which request and | |
| response attributes do not need hashing in the audit logs. |
schavis
reviewed
Jul 25, 2025
Address feedback on writing style (hashicorpGH-631)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Revamp the documentation for Vault's audit logging. Changes include:
These changes cover most of VSM-226 and were reviewed internally by Engineering and Resident Architects/Engineers from the Professional Services team (see Google Docs history).
The changes also include minor fixes for the Audit Filtering docs page, which were identified in the course of Engineering review.